BCI NET

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET / BCI NET Dec 94.iso / archives / programming / source / jade-3.2.lha / jade-3.2 / man / jade.info-6 < prev next >

Wrap

GNU Info File | 1994-10-16 | 47.6 KB | 1,334 lines

This is Info file jade.info, produced by Makeinfo-1.55 from the input file jade.texi. START-INFO-DIR-ENTRY * Jade: (jade). An editor for X11 and AmigaDOS END-INFO-DIR-ENTRY This is Edition 1.3, last updated 7 October 1994, of `The Jade Manual', for Jade, Version 3.2. Jade is a text editor for X11 (on Unix) and the Amiga. Copyright 1993, 1994 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. File: jade.info, Node: Macro Expansion, Next: Compiling Macros, Prev: Defining Macros, Up: Macros Macro Expansion --------------- When a macro call is detected (*note List Forms::.) the function which is the cdr of the macro's definition (*note Defining Macros::.) is applied to the macro call's arguments. Unlike in a function call, the arguments are *not evaluated*, the actual forms are the arguments to the macro's expansion function. This is so these forms can be rearranged by the macro's expansion function to create the new form which will be evaluated. There is a function which performs macro expansion, its main use is to let the Lisp compiler expand macro calls at compile time. - Function: macroexpand FORM &optional ENVIRONMENT If FORM is a macro call `macroexpand' will expand that call by calling the macro's expansion function (the cdr of the macro definition). If this expansion is another macro call the process is repeated until an expansion is obtained which is not a macro call, this form is then returned. The optional ENVIRONMENT argument is an alist of macro definitions to use as well as the existing macros; this is mainly used for compiling purposes. (defmacro when (condition &rest body) "Evaluates CONDITION, if it's non-`nil' evaluates the BODY forms." (list 'if condition (cons 'progn body))) => when (macroexpand '(when x (setq foo bar))) => (if x (progn (setq foo bar))) File: jade.info, Node: Compiling Macros, Prev: Macro Expansion, Up: Macros Compiling Macros ---------------- Although it may seem odd that macros return a form to produce a result and not simply the result this is their most important feature. It allows the expansion and the evaluation of the expansion to happen at different times. The Lisp compiler makes use of this; when it comes across a macro call in a form it is compiling it uses the `macroexpand' function to produce the expansion of that form which it then compiles straight into the object code. Obviously this is good for performance (why evaluate the expansion every time it is needed when once will do?). Some rules do need to be observed to make this work properly: * When the compiler compiles a file it remembers the macros which have been defined by that file; it can only expand a macro call if the definition of the macro appears before the macro call itself (it can't read your mind). * The macro expansion function (i.e. the definition of the macro) should not have any side effects or evaluate its arguments (the value of a symbol at compile-time probably won't be the same as its value at run-time). * Macros which are defined by another file must be loaded so they can be recognised. Use the `require' function, the compiler will evaluate any top-level `require' forms it sees to bring in any macro definitions used. File: jade.info, Node: Streams, Next: Loading, Prev: Macros, Up: Programming Jade Streams ======= A "stream" is a Lisp object which is either a data sink (an "output stream") or a data source (an "input stream"). In Jade all streams produce or consume sequences of 8-bit characters. Streams are very flexible, functions using streams for their input and output do not need to know what type of stream it is. For example the Lisp reader (the `read' function) takes an input stream as its one argument, it then reads characters from this stream until it has parsed a whole object. This stream could be a file, a position in a buffer, a function or even a string; the `read' function can not tell the difference. - Function: streamp OBJECT This function returns `t' if its argument is a stream. * Menu: * Input Streams:: Types of input stream * Output Streams:: Types of output stream * Input Functions:: Functions to read from streams * Output Functions:: How to output to a stream File: jade.info, Node: Input Streams, Next: Output Streams, Up: Streams Input Streams ------------- These are the possible types of input stream, for the functions which use them see *Note Input Functions::. `FILE' Characters are read from the file object FILE, for the functions which manipulate file objects see *Note Files::. `MARK' The marker MARK points to the next character that will be read. Each time a character is read the position that MARK points to will be advanced to the following character. *Note Marks::. `BUFFER' Reads from the position of the cursor in the buffer BUFFER. This position is advanced as characters are read. `(BUFFER . POSITION)' Characters are read from the position POSITION in the buffer BUFFER. POSITION is advanced to the next character as each character is read. `FUNCTION' Each time an input character is required the FUNCTION is called with no arguments. It should return the character read (an integer) or `nil' if for some reason no character is available. FUNCTION should also be able to `unread' one character. When this happens the function will be called with one argument -- the value of the last character read. The function should arrange it so that the next time it is called it returns this character. A possible implementation could be, (defvar ms-unread-char nil "If non-nil the character which was pushed back.") (defun my-stream (&optional unread-char) (if unread-char (setq ms-unread-char unread-char) (if ms-unread-char (prog1 ms-unread-char (setq ms-unread-char nil)) ;; Normal case -- read and return a character from somewhere ... `nil' Read from the stream stored in the variable `standard-input'. It is also possible to use a string as an input stream. The string to be read from must be applied to the `make-string-input-stream' function and the result from this function used as the input stream. - Function: make-string-input-stream STRING &optional START Returns an input stream which will supply the characters of the string STRING in order starting with the character at position START (or from position zero if this argument is undefined). (read (make-string-input-stream "(1 . 2)")) => (1 . 2) - Variable: standard-input The input stream which is used when no other is specified or is `nil'. File: jade.info, Node: Output Streams, Next: Input Functions, Prev: Input Streams, Up: Streams Output Streams -------------- These are the different types of output stream, for the functions which use them see *Note Output Functions::. `FILE' Writes to the file object FILE. *Note Files::. `MARK' Writes to the position pointed to by the marked MARK, then advances the position of the mark. `BUFFER' Writes to BUFFER at the position of the cursor in that buffer, which is then advanced. `(BUFFER . POSITION)' POSITION in the buffer BUFFER. POSITION is then moved over the written text. `(BUFFER . t)' Writes to the end of the buffer BUFFER. `FUNCTION' The function FUNCTION is called with one argument, either a string or a character. This should be used as the circumstances dictate. If the function returns a number it is the number of characters actually used, otherwise it is assumed that all the characters were successful. `PROCESS' Writes to the standard input of the process object PROCESS. If PROCESS isn't running an error is signalled. *Note Processes::. `t' Appends the character(s) to the end of the status line message. `nil' Write to the stream stored in the variable `standard-output'. It is also possible to store the characters sent to an output stream in a string. - Function: make-string-output-stream Returns an output stream. It accumulates the text sent to it for the benefit of the `get-output-stream-string' function. - Function: get-output-stream-string STRING-OUTPUT-STREAM Returns a string consisting of the text sent to the STRING-OUTPUT-STREAM since the last call to GET-OUTPUT-STREAM-STRING (or since this stream was created by `make-string-output-stream'). (setq stream (make-string-output-stream)) => ("" . 0) (prin1 keymap-path stream) => ("(lisp-mode-keymap global-keymap)" . 64) (get-output-stream-string stream) => "(lisp-mode-keymap global-keymap)" - Variable: standard-output This variable contains the output stream which is used when no other is specified (or when the given output stream is `nil'). File: jade.info, Node: Input Functions, Next: Output Functions, Prev: Output Streams, Up: Streams Input Functions --------------- - Function: read-char STREAM Read and return the next character from the input stream STREAM. If the end of the stream is reached `nil' is returned. - Function: read-line STREAM This function reads one line of characters from the input stream STREAM, creates a string containing the line (including the newline character which terminates the line) and returns it. If the end of stream is reached before any characters can be read `nil' is returned, if the end of stream is reached but some characters have been read (but not the newline) these characters are made into a string and returned. Note that unlike the Common Lisp function of the same name, the newline character is not removed from the returned string. - Function: read STREAM This function is the function which contains the Lisp reader (*note The Lisp Reader::.). It reads as many characters from the input stream STREAM as it needs to make the read syntax of a single Lisp object (*note Read Syntax::.), this object is then returned. - Function: read-from-string STRING &optional START Reads one Lisp object from the string STRING, the first character is read from position START (or position zero). (read-from-string STRING START) == (read (make-string-input-stream STRING START)) File: jade.info, Node: Output Functions, Prev: Input Functions, Up: Streams Output Functions ---------------- - Function: write STREAM DATA &optional LENGTH Writes the specified character(s) to the output stream STREAM. dATA is either the character or the string to be written. If DATA is a string the optional argument LENGTH may specify how many characters are to be written. The value returned is the number of characters successfully written. (write standard-output "Testing 1.. 2.. 3..") -| Testing 1.. 2.. 3.. => 19 - Function: copy-stream INPUT-STREAM OUTPUT-STREAM This function copies all characters which may be read from INPUT-STREAM to OUTPUT-STREAM. The copying process is not stopped until the end of the input stream is read. Returns the number of characters copied. Be warned, if you don't choose the streams carefully you may get a deadlock which only an interrupt signal can break! - Function: print OBJECT &optional STREAM Outputs a newline character to the output stream STREAM, then writes a textual representation of OBJECT to the stream. If possible, this representation will be such that `read' can turn it into an object structurally similar to OBJECT. This will *not* be possible if OBJECT does not have a read syntax. OBJECT is returned. (print '(1 2 3)) -| -| (1 2 3) => (1 2 3) - Function: prin1 OBJECT &optional STREAM Similar to `print' but no initial newline is output. (prin1 '(1 2 3)) -| (1 2 3) => (1 2 3) (prin1 '|(xy((z]|) ;A strange symbol -| \(xy\(\(z\] => \(xy\(\(z\] - Function: prin1-to-string OBJECT Returns a string containing the characters that `prin1' would output when it prints OBJECT. (prin1-to-string '(1 2 3)) => "(1 2 3)" - Function: princ OBJECT &optional STREAM Prints a textual representation of OBJECT to the output stream STREAM. No steps are taken to create output that `read' can parse and no quote characters surround strings. (princ "foo") -| foo => "foo" (princ '|(xy((z]|) -| (xy((z] => \(xy\(\(z\] - Function: format STREAM TEMPLATE &rest VALUES Writes to a stream, STREAM, a string constructed from the format string, TEMPLATE, and the argument VALUES. If STREAM is `nil' the resulting string will be returned, not written to a stream. TEMPLATE is a string which may contain format specifiers, these are a `%' character followed by another character telling how to print the next of the VALUES. The following options are available `s' Write the printed representation of the value without quoting (as if from the `princ' function). `S' Write the printed representation *with* quoting enabled (like the `prin1' function). `d' Output the value as a decimal number. `o' Write the value in octal. `x' In hexadecimal. `c' Write the character specified by the value. `%' Print a literal percent character. None of the VALUES are used. The function works through the TEMPLATE a character at a time. If the character is a format specifier (a `%') it inserts the correct string (as defined above) into the output. Otherwise, the character is simply put into the output stream. If STREAM isn't `nil' (i.e. the formatted string is returned) the value of STREAM is returned. (format nil "foo %S bar 0x%x" '(x . y) 255) => "foo (x . y) bar 0xff" (format standard-output "The %s is %s!" "dog" "purple") -| The dog is purple! => #<buffer *jade*> File: jade.info, Node: Loading, Next: Compiled Lisp, Prev: Streams, Up: Programming Jade Loading ======= In Lisp, programs (also called "modules") are stored in files. Each file is a sequence of Lisp forms (known as "top-level forms"). Most of the top-level forms in a program will be definitions (i.e. function, macro or variable definitions) since generally each module is a system of related functions and variables. Before the program can be used it has to be "loaded" into the editor's workspace; this involves reading and evaluating each top-level form in the file. * Menu: * Load Function:: The function which loads programs * Autoloading:: Functions can be loaded on reference * Features:: Module management functions File: jade.info, Node: Load Function, Next: Autoloading, Up: Loading Load Function ------------- - Function: load PROGRAM &optional NO-ERROR NO-PATH NO-SUFFIX This function loads the file containing the program called PROGRAM; first the file is located then each top-level form contained by the file is read and evaluated in order. Each directory named by the variable `load-path' is searched until the file containing PROGRAM is found. In each directory three different file names are tried, 1. PROGRAM with `.jlc' appended to it. Files with a `.jlc' suffix are usually compiled Lisp files. *Note Compiled Lisp::. 2. PROGRAM with `.jl' appended, most uncompiled Lisp programs are stored in files with names like this. 3. PROGRAM with no modifications. If none of these gives a result the next directory is searched in the same way, when all directories in `load-path' have been exhausted and the file still has not been found an error is signalled. Next the file is opened for reading and Lisp forms are read from it one at a time, each form is evaluated before the next form is read. When the end of the file is reached the file has been loaded and this function returns `t'. The optional arguments to this function are used to modify its behaviour, NO-ERROR When this argument is non-`nil' no error is signalled if the file can not be located. Instead the function returns `nil'. NO-PATH The variable `load-path' is not used, PROGRAM must point to the file from the current working directory. NO-SUFFIX When non-`nil' no `.jlc' or `.jl' suffixes are applied to the PROGRAM argument when locating the file. If a version of the program whose name ends in `.jlc' is older than a `.jl' version of the same file (i.e. the source code is newer than the compiled version) a warning is displayed and the `.jl' version is used. (load "foobar") error--> File error: Can't open lisp-file, foobar (load "foobar" t) => nil - Variable: load-path A list of strings, each element is the name of a directory which is prefixed to the name of a program when Lisp program files are being searched for. load-path => ("" "/usr/local/lib/jade/3.2/lisp/") The element `""' means the current directory, note that directory names should have an ending `/' (or whatever) so that when concatenated with the name of the file they make a meaningful filename. - Variable: lisp-lib-dir The name of the directory in which the standard Lisp files are stored. lisp-lib-dir => "/usr/local/lib/jade/3.2/lisp/" File: jade.info, Node: Autoloading, Next: Features, Prev: Load Function, Up: Loading Autoloading ----------- Obviously, not all the features of the editor are always used. "Autoloading" allows modules to be loaded when they are referenced. This speeds up the initialisation process and may save memory. Functions which may be autoloaded have a special form in their symbol's function cell -- an autoload form. This is a list whose first element is the symbol `autoload'. When the function call dispatcher finds one of these forms it loads the program file specified in the form then re-evaluates the function call. The true function definition will have been loaded and therefore the call may proceed as normal. The structure of an autoload form is: (autoload PROGRAM-FILE [IS-COMMAND]) PROGRAM-FILE is the argument to give to the `load' function when the function is to be loaded. It should be the program containing a definition of the autoloaded function. The optional IS-COMMAND object specifies whether or not the function may be called interactively (i.e. it is an editor command). - Function: autoload SYMBOL &rest AUTOLOAD-DEFN Installs an autoload form into the function cell of the symbol SYMBOL. The form is a cons cell whose car is `autoload' and whose cdr is the argument AUTOLOAD-DEFN. Returns the resulting autoload form. (autoload 'foo "foos-file") => (autoload "foos-file") (symbol-function 'foo) => (autoload "foos-file") (autoload 'bar "bars-file" t) => (autoload "bars-file" t) (commandp 'bar) => t It is not necessary to call the `autoload' function manually. Simply prefix the definitions of all the functions which may be autoloaded (i.e. the entry points to your module; *not* all the internal functions!) with the magic comment `;;;###autoload'. Then the `add-autoloads' command can be used to create the necessary calls to the autoload function in the `autoloads.jl' Lisp file (this file which lives in the Lisp library directory is loaded when the editor is initialised). `Meta-x add-autoloads' Scans the current buffer for any autoload definitions. Functions with the comment `;;;###autoload' preceding them have autoload forms inserted into the `autoloads.jl' file. Simply save this file's buffer and the new autoloads will be used the next time Jade is initialised. It is also possible to mark arbitrary forms for inclusion in the `autoloads.jl' file: put them on a single line which starts with the comment `;;;###autoload' call the command. The unsaved `autoloads.jl' buffer will become the current buffer. ;;;###autoload (defun foo (bar) ;`foo' is to be autoloaded ... ;;;###autoload (setq x y) ;Form to eval on initialisation `Meta-x remove-autoloads' Remove all autoload forms from the `autoloads.jl' file which are marked by the `;;;###autoload' comment in the current buffer. The unsaved `autoloads.jl' buffer will become the current buffer. File: jade.info, Node: Features, Prev: Autoloading, Up: Loading Features -------- "Features" correspond to modules of the editor. Each feature is loaded separately. Each feature has a name, when a certain feature is required its user asks for it to be present (with the `require' function), the feature may then be used as normal. When a feature is loaded one of the top-level forms evaluated is a call to the `provide' function. This names the feature and installs it into the list of present features. - Variable: features A list of the features currently present (that is, loaded). Each feature is represented by a symbol. Usually the print name of the symbol (the name of the feature) is the same as the name of the file it was loaded from, minus any `.jl' or `.jlc' suffix. features => (info isearch fill-mode texinfo-mode lisp-mode xc) - Function: provide FEATURE Adds FEATURE (a symbol) to the list of features present. A call to this function is normally one of the top-level forms in a module. ;;;; maths.jl -- the `maths' module (provide 'maths) ... - Function: require FEATURE &optional FILE Show that the caller is planning to use the feature FEATURE (a symbol). This function will check the `features' variable to see if FEATURE is already loaded, if so it will return immediately. If FEATURE is not present it will be loaded. If FILE is non-`nil' it specifies the first argument to the `load' function, else the print name of the symbol FEATURE is used. ;;;; physics.jl -- the `physics' module (require 'maths) ;Need the `maths' module (provide 'physics) ... File: jade.info, Node: Compiled Lisp, Next: Hooks, Prev: Loading, Up: Programming Jade Compiled Lisp ============= Jade contains a rudimentary Lisp compiler; this takes a Lisp form or program and compiles it into a "byte-code" form. This byte-code form contains a string of byte instructions, a vector of data constants and some other information. The main reason for compiling your programs is to increase their speed, it is difficult to quantify the speed increase gained -- some programs (especially those using a lot of macros) will execute many times quicker than their uncompiled version whereas others may only execute a bit quicker. * Menu: * Compilation Functions:: How to compile Lisp programs * Compilation Tips:: Getting the most out of the compiler * Disassembly:: Examining compiled functions File: jade.info, Node: Compilation Functions, Next: Compilation Tips, Up: Compiled Lisp Compilation Functions --------------------- - Function: compile-form FORM This function compiles the Lisp form FORM into a byte-code form which is returned. (compile-form '(setq foo bar)) => (jade-byte-code "F!" [bar foo] 2) - Command: compile-file FILE-NAME This function compiles the file called FILE-NAME into a file of compiled Lisp forms whose name is FILE-NAME with `c' appended to it (i.e. if FILE-NAME is `foo.jl' it will be compiled to `foo.jlc'). If an error occurs while the file is being compiled any semi-written file will be deleted. When called interactively this function will ask for the value of FILE-NAME. - Command: compile-directory DIRECTORY &optional FORCE EXCLUDE Compiles all the Lisp files in the directory called DIRECTORY which either haven't been compiled or whose compiled version is older than the source file (Lisp files are those ending in `.jl'). If the optional argument FORCE is non-`nil' *all* Lisp files will be recompiled whatever the status of their compiled version. The EXCLUDE argument may be a list of filenames, these files will *not* be compiled. When this function is called interactively it prompts for the directory. - Function: compile-lisp-lib &optional FORCE Uses `compile-directory' to compile the library of standard Lisp files. If FORCE is non-`nil' all of these files will be compiled. The `autoloads.jl' is *never* compiled since it is often modified and wouldn't really benefit from compilation anyway. - Function: jade-byte-code BYTE-CODES CONSTANTS MAX-STACK Interprets the string of byte instructions BYTE-CODES with the vector of constants CONSTANTS. MAX-STACK defines the maximum number of stack cells required to interpret the code. This function is *never* called by hand. The compiler will produce calls to this function when it compiles a form or a function. (setq x 1 y 3) => 3 (setq comp (compile-form '(cons x y))) => (jade-byte-code "K" [x y] 2) (eval comp) => (1 . 3) File: jade.info, Node: Compilation Tips, Next: Disassembly, Prev: Compilation Functions, Up: Compiled Lisp Compilation Tips ---------------- Here are some tips for making compiled code run fast: * Always favour iteration over recursion; function calls are relatively slow. The compiler doesn't know about tail recursion or whatever so you'll have to do this explicitly. For example, the most elegant way of searching a list is to use recursion, (defun scan-list (list elt) "Search the LIST for an element ELT. Return it if one is found." (if (eq (car list) elt) elt (scan-list (cdr list) elt))) but this is fairly slow. Instead, iterate through each element, (defun scan-list (list elt) (while (consp list) (when (eq (car list) elt) (return elt)) (setq list (cdr list)))) * In some cases the functions `member', `memq', `assoc', etc... can be used to search lists. Since these are primitives written in C they will run *much* faster than an equivalent Lisp function. So the above `scan-list' example can be rewritten as, (defun scan-list (list elt) (car (memq elt list))) Also note that the `mapcar' and `mapc' functions are useful (and efficient) when using lists. * Whenever possible use the `when' and `unless' conditional structures; they are more efficient than `cond' or `if'. * Careful use of named constants (*note Constant Variables::.) can increase the speed of some programs. For example, in the Lisp compiler itself all the opcode values (small integers) are defined as constants. I must stress that in some cases constants are *not* suitable; they may drastically increase the size of the compiled program (when the constants are `big' objects, i.e. long lists) or even introduce subtle bugs (since two references to the same constant may not be `eq' whereas two references to the same variable are always `eq'). * Many primitives have corresponding byte-code instructions; these primitives will be quicker to call than those that don't (and incur a normal function call). Currently, the functions which have byte-code instructions (apart from all the special forms) are: `cons', `car', `cdr', `rplaca', `rplacd', `nth', `nthcdr', `aset', `aref', `length', `eval', `+', `*', `/', `%', `lognot', `not', `logior', `logand', `equal', `eq', `=', `/=', `>', `<', `>=', `<=', `1+', `1-', `-', `set', `fset', `lsh', `zerop', `null', `atom', `consp', `listp', `numberp', `stringp', `vectorp', `throw', `fboundp', `boundp', `symbolp', `get', `put', `signal', `return', `reverse', `nreverse', `assoc', `assq', `rassoc', `rassq', `last', `mapcar', `mapc', `member', `memq', `delete', `delq', `delete-if', `delete-if-not', `copy-sequence', `sequencep', `functionp', `special-formp', `subrp', `eql', `set-current-buffer', `current-buffer', `bufferp', `markp', `windowp'. * When a file is being compiled each top-level form it contains is inspected to see if it should be compiled into a byte-code form. Different types of form are processed in different ways: * Function and macro definitions have their body forms compiled into a single byte-code form. The doc-string and interactive declaration are not compiled. * Calls to the `require' function are evaluated then the unevaluated form is written as-is to the output file. The reason it is evaluated is so that any macros defined in the required module are loaded before they are called by the program being compiled. * If the form is a list form (*note List Forms::.) and the symbol which is the car of the list is one of: `if', `cond', `when', `unless', `let', `let*', `catch', `unwind-protect', `error-protect', `with-buffer', `with-window', `progn', `prog1', `prog2', `while', `and', `or'. then the form is compiled. Otherwise it is just written to the output file in its uncompiled state. If your program contains a lot of top-level forms which you know will not be compiled automatically, consider putting them in a `progn' block to make the compiler coalesce them into one byte-code form. File: jade.info, Node: Disassembly, Prev: Compilation Tips, Up: Compiled Lisp Disassembly ----------- It is possible to disassemble byte-code forms; originally this was so I could figure out why the compiler wasn't working but if you're curious about how the compiler compiles a form it may be of use to you. Naturally, the output of the disassembler is a listing in Jade's pseudo-machine language -- it won't take a byte-code form and produce the equivalent Lisp code! - Command: disassemble-fun FUNCTION &optional STREAM This function disassembles the compile Lisp function FUNCTION. It writes a listing to the output stream STREAM (normally the value of the `standard-output' variable). When called interactively it will prompt for a function to disassemble. When reading the output of the disassembler bear in mind that Jade simulates a stack machine for the code to run on. All calculations are performed on the stack, the value left on the stack when the piece of code ends is the value of the byte-code form. File: jade.info, Node: Hooks, Next: Buffers, Prev: Compiled Lisp, Up: Programming Jade Hooks ===== A "hook" allows you to wedge your own pieces of Lisp code into the editor's operations. These pieces of code are evaluated via the hook and the result is available to the hook's caller. * Menu: * Functions As Hooks:: Some hooks are a single function, * Normal Hooks:: Others may be a list of pieces of code to evaluate. * Standard Hooks:: A table of the predefined hooks File: jade.info, Node: Functions As Hooks, Next: Normal Hooks, Up: Hooks Functions As Hooks ------------------ Some hooks only allow a single piece of code to be hooked in. Usually a normally-undefined function is used; to install your hook defined a function with the name of the hook. When the hook is to be evaluated the function is called. Generally the name of the hook's function will end in `-function'. An alternative scheme is to use a variable to store the hook, its value should be the function to call. File: jade.info, Node: Normal Hooks, Next: Standard Hooks, Prev: Functions As Hooks, Up: Hooks Normal Hooks ------------ This is the standard type of hook, it is a variable whose value is a list of functions. When the hook is evaluated each of the named functions will be called in turn until one of them returns a value which is not `nil'. This value becomes the value of the hook and no more of the functions are called. If all of the functions in the hook return `nil' the value of the hook is `nil'. The names of hooks of this type will normally end in `-hook'. - Function: add-hook HOOK FUNCTION &optional AT-END This function adds a new function FUNCTION to the list of functions installed in the (list) hook HOOK (a symbol). If AT-END is non-`nil' the new function is added at the end of the hook's list of functions (and therefore will be called last when the hook is evaluated), otherwise the new function is added to the front of the list. text-mode-hook => (fill-mode-on) (add-hook 'text-mode-hook 'my-function) => (my-function fill-mode-on) - Function: remove-hook HOOK FUNCTION This function removes the function FUNCTION from the list of functions stored in the (list) hook HOOK (a symbol). *All* instances of FUNCTION are deleted from the hook. text-mode-hook => (my-function fill-mode-on) (remove-hook 'text-mode-hook 'my-function) => (fill-mode-on) - Function: eval-hook HOOK &rest ARGS Evaluates the (list) hook HOOK (a symbol) with argument values ARGS. Each function stored in the hook is applied to the ARGS in turn until one returns non-`nil'. This non-`nil' value becomes the result of the hook. If all functions return `nil' then the result of the hook is `nil'. Note that most functions which are installed in hooks should always return `nil' to ensure that all the functions in the hook are evaluated. File: jade.info, Node: Standard Hooks, Prev: Normal Hooks, Up: Hooks Standard Hooks -------------- This is a table of the predefined hooks in Jade: `asm-cpp-mode-hook' *Note Asm mode::. `asm-mode-hook' *Note Asm mode::. `auto-save-hook' *Note Controlling Auto-Saves::. `buffer-menu-mode-hook' `c-mode-hook' *Note C mode::. `destroy-window-hook' *Note Closing Windows::. `gdb-hook' `idle-hook' *Note Idle Actions::. `indented-text-mode-hook' *Note Indented-Text mode::. `insert-file-hook' *Note Reading Files Into Buffers::. `kill-buffer-hook' *Note Destroying Buffers::. `lisp-mode-hook' *Note Lisp mode::. `make-window-hook' *Note Opening Windows::. `open-file-hook' *Note Reading Files Into Buffers::. `read-file-hook' *Note Reading Files Into Buffers::. `shell-callback-function' `shell-mode-hook' `texinfo-mode-hook' *Note Texinfo mode::. `text-mode-hook' *Note Text mode::. `unbound-key-hook' *Note Event Loop::. `window-closed-hook' *Note Event Loop::. `write-file-hook' *Note Writing Buffers::. File: jade.info, Node: Buffers, Next: Windows, Prev: Hooks, Up: Programming Jade Buffers ======= A "buffer" is a Lisp object containing a `space' in which files (or any pieces of text) may be edited, either directly by the user or by Lisp programs. Each window (*note Windows::.) may display any one buffer at any time, the buffer being displayed by the current window is known as the "current buffer". This is the buffer which functions will operate on by default. - Function: bufferp OBJECT Returns `t' if its argument is a buffer. * Menu: * Buffer Attributes:: Data contained in a buffer object * Creating Buffers:: How to create empty buffers * Modifications to Buffers:: Is a buffer modified? * Read-Only Buffers:: Unmodifiable buffers * Destroying Buffers:: Deleting a buffer and its contents * Special Buffers:: Program-controlled buffers * The Buffer List:: Each window has a list of buffers * The Current Buffer:: One buffer is the default buffer File: jade.info, Node: Buffer Attributes, Next: Creating Buffers, Up: Buffers Buffer Attributes ----------------- All buffer objects store a set of basic attributes, some of these are: "name" Each buffer has a unique name. - Function: buffer-name &optional BUFFER Returns the name of the buffer BUFFER, or of the current buffer if BUFFER is undefined. (buffer-name) => "programmer.texi" - Function: set-buffer-name NAME &optional BUFFER Sets the name of the buffer BUFFER (or the current buffer) to the string NAME. Note that NAME is not checked for uniqueness, use the `make-buffer-name' function if you want a guaranteed unique name. - Function: make-buffer-name NAME Returns a unique version of the string NAME so that no existing buffer has the same string as its name. If a clash occurs a suffix `<N>' is appended to NAME, where N is the first number which guarantees the uniqueness of the result. - Function: get-buffer NAME Returns the existing buffer whose name is NAME, or `nil' if no such buffer exists. "file name" Since buffers often contain text belonging to files on disk the buffer stores the name of the file its text was read from. *Note Editing Files::. - Function: buffer-file-name &optional BUFFER Returns the name of the file stored in BUFFER. If no file is stored in the buffer the null string (`') is returned. (buffer-file-name) => "man/programmer.texi" - Function: set-buffer-file-name NAME &optional BUFFER This function sets the file-name of the buffer to the string NAME. - Function: get-file-buffer FILE-NAME Searches for an existing buffer containing the file FILE-NAME then returns it, or `nil' if no such buffer exists. "contents" The contents of a buffer is the text it holds. This is stored as an array of lines. *Note Text::. "tab size" This is the spacing of tab stops. When the contents of the buffer is being displayed (in a window) this value is used. - Variable: tab-size A buffer-local variable which holds the size of tab stops in the buffer. "glyph table" Each buffer has its own glyph table which is used when the buffer is being displayed. *Note Buffer Glyph Tables::. "local variables" Each buffer can have its own value for any variable, these local values are stored in an alist which lives in the buffer object. *Note Buffer-Local Variables::. - Function: buffer-variables &optional BUFFER Returns the alist of local variables in the buffer. Each alist element is structured like, `(SYMBOL . LOCAL-VALUE)'. "modification counter" Each modification made to the buffer increments its modification counter. *Note Modifications to Buffers::. - Function: buffer-changes &optional BUFFER Returns the number of modifications made to the buffer since it was created. "undo information" When a modification is made to a buffer enough information is recorded so that the modification can later be undone. *Note Controlling Undo::. All other buffer-specific information is kept in buffer-local variables. File: jade.info, Node: Creating Buffers, Next: Modifications to Buffers, Prev: Buffer Attributes, Up: Buffers Creating Buffers ---------------- - Function: make-buffer NAME Creates and returns a new buffer object. Its name will be a unique version of NAME (created by the `make-buffer-name' function). The buffer will be totally empty and all its attributes will have standard values. (make-buffer "foo") => #<buffer foo> - Function: open-buffer NAME If no buffer called NAME exists, creates a new buffer of that name and adds it to the end of each windows `buffer-list'. This function always returns the buffer called NAME. For more ways of creating buffers see *Note Editing Files::. File: jade.info, Node: Modifications to Buffers, Next: Read-Only Buffers, Prev: Creating Buffers, Up: Buffers Modifications to Buffers ------------------------ Each buffer maintains a counter which is incremented each time the contents of the buffer is modified. It also holds the value of this counter when the buffer was last saved, when the two numbers are different the buffer is classed as have being "modified". - Function: buffer-modified-p &optional BUFFER This function returns `t' when the buffer has been modified. - Function: set-buffer-modified BUFFER STATUS Sets the modified status of the buffer BUFFER. When STATUS is `nil' the buffer will appear to be unmodified, otherwise it will look modified. File: jade.info, Node: Read-Only Buffers, Next: Destroying Buffers, Prev: Modifications to Buffers, Up: Buffers Read-Only Buffers ----------------- When a buffer has been marked as being read-only no modifications may be made to its contents (neither by the user nor a Lisp program). - Function: buffer-read-only-p &optional BUFFER Returns `t' when the buffer is read-only. - Function: set-buffer-read-only BUFFER READ-ONLY When READ-ONLY is non-`nil' the buffer BUFFER is marked as being read-only, otherwise it is read-write. - Variable: inhibit-read-only When this variable is non-`nil' any buffer may be modified, even if it is marked as being read-only. Lisp programs can temporarily bind a non-`nil' value to this variable when they want to edit one of their normally read-only buffers. File: jade.info, Node: Destroying Buffers, Next: Special Buffers, Prev: Read-Only Buffers, Up: Buffers Destroying Buffers ------------------ Since all Lisp objects have indefinite extent (i.e. they live until there are no references to them) a buffer will be automatically destroyed when all references to it disappear. Alternatively one of the following functions can be used to explicitly kill a buffer; the buffer object will still exist but all data associated with it (including the text it contains) will be released. - Command: kill-buffer BUFFER Removes the buffer BUFFER (a buffer or the name of a buffer) from all windows (any windows displaying BUFFER will be changed to display the previous buffer they showed) and destroys the buffer. The hook `kill-buffer-hook' is evaluated before the buffer is killed with BUFFER as its argument. If the buffer contains unsaved modifications the user will be asked if they really want to lose them before the buffer is killed (if the answer is yes). When called interactively a buffer will be prompted for. - Hook: kill-buffer-hook Hook called by `kill-buffer' before it does anything. If a function in the hook doesn't want the buffer deleted it should signal some sort of error. - Function: destroy-buffer BUFFER This function may be used to remove all data stored in the buffer object manually. Also, any marks in this buffer are made non-resident. After applying this function to a buffer the buffer will contain one empty line. Use this function wisely, there are no safety measures taken to ensure valuable data is not lost. File: jade.info, Node: Special Buffers, Next: The Buffer List, Prev: Destroying Buffers, Up: Buffers Special Buffers --------------- When a buffer is "special" it means that it is controlled by a Lisp program, not by the user typing into it (although this can happen as well). Special buffers are used for things like the `*jade*' or `*Info*' buffers (in fact most of the buffers whose names are surrounded by asterisks are special). What the special attribute actually does is make sure that the buffer is never truly killed (`kill-buffer' removes it from each window's `buffer-list' but doesn't call `destroy-buffer' on it) and modifications don't cause the `+' flag to appear in the status line. - Function: buffer-special-p &optional BUFFER Returns `t' if the buffer is marked as being special. - Function: set-buffer-special BUFFER SPECIAL Sets the value of the special flag in the buffer BUFFER to the value of SPECIAL (`nil' means non-special, anything else means special). Another type of special buffer exists; the "mildly-special buffer". - Variable: mildly-special-buffer When this buffer-local variable is set to `t' (it is `nil' by default) and the buffer is marked as being special, the `kill-buffer' function is allowed to totally destroy the buffer. File: jade.info, Node: The Buffer List, Next: The Current Buffer, Prev: Special Buffers, Up: Buffers The Buffer List --------------- Each window (*note Windows::.) has a list of buffers which may be displayed in that window. It is arranged is "most-recently-used" order, so that the car of the list is the buffer currently being shown in the window, the second element the window previously being shown and so on. - Variable: buffer-list A variable, local to each window, which contains a list of the buffers available in the window. The list is maintained in most-recently-used order. buffer-list => (#<buffer programmer.texi> #<buffer *Help*> #<buffer buffers.c> #<buffer buffers.jl> #<buffer edit.c> #<buffer edit.h> #<buffer *jade*> #<buffer lisp.jl> #<buffer *compilation*> #<buffer *Info*>) Generally each window's `buffer-list' contains the same buffers, each window has its own value for the variable so it can be kept in the correct order (each window will probably be displaying different buffers). - Function: add-buffer BUFFER This function ensures that the buffer BUFFER is in each window's `buffer-list'. If it isn't it is appended to the end of the list. - Function: remove-buffer BUFFER Deletes all references to BUFFER in each window's `buffer-list'. - Command: bury-buffer &optional BUFFER ALL-WINDOWS Puts BUFFER (or the currently displayed buffer) at the end of the current window's `buffer-list' then switch to the buffer at the head of the list. If ALL-WINDOWS is non-`nil' this is done in all windows (the same buffer will be buried in each window though). - Command: rotate-buffers-forward Moves the buffer at the head of the `buffer-list' to be last in the list, the new head of the `buffer-list' is displayed in the current window.